/*
 * ConfigurationFileUtil.java    0.0.1    01/ott/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.utils;

import java.io.IOException;
import java.util.Enumeration;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * Utility class to read and write configuration, and store/save them from a file.
 * <p>
 * It acts as facade to heterogeneous file / properites formats such as the built-in
 * JDK Properties file, or JSON (http://json.org) properties files.
 * </p>
 * @version    0.0.1    01/ott/2009    
 * @author     Andrea Reale <andrea.reale@gmail.com>
 *
 */
public abstract class ConfigurationFileUtil {
    
    protected final static Logger log = LoggerFactory.getLogger(ConfigurationFileUtil.class);
    
    public final static Class<? extends ConfigurationFileUtil> DEFAULT_CONF_UTIL = 
	JDKPropertiesConfFileUtil.class;
    
    public final static String DEFAULT_ENCODING = "UTF-8";
    
    /**
     * Instantiates a <tt>ConfigurationFileUtil</tt>.
     * <p>
     * The actual type of the util that is instantiated depends on the value of
     * the field {@link #DEFAULT_CONF_UTIL} 
     * </p>
     * @return an instance of <tt>ConfigurationFileUtil</tt>
     */
    public static ConfigurationFileUtil newConfUtil() {
	try {
	    return DEFAULT_CONF_UTIL.newInstance();
	} catch (Exception e) {
	    String msg = "Cannot instantiate ConfigurationFileUtil of class " + DEFAULT_CONF_UTIL.getSimpleName();
	    log.error(msg);
	} 
	return null;
    }
    
    /**
     * Sets an integer property in this configuration.
     * <p>
     * That property will be associated to the given key. If there already
     * was a property associated to that key, that property gets overwritten
     * </p>
     * @param key the key of the property to set
     * @param value the value of the property
     */
    public abstract void setIntProperty(String key, int value);
    /**
     * Gets an integer property from this configuration.
     * <p>
     * That property associated to the given key will be returned. If there is
     * no property associated to the given key, <code>0</code> is returned
     * </p>
     * @param key the key of the property to set
     * @return value the value of the property
     */
    public abstract int getIntProperty(String key);
    
    /**
     * Sets a boolean property in this configuration.
     * <p>
     * That property will be associated to the given key. If there already
     * was a property associated to that key, that property gets overwritten
     * </p>
     * @param key the key of the property to set
     * @param value the value of the property
     */
    public abstract void setBooleanProperty(String key, boolean value);
    
    /**
     * Gets a boolean property from this configuration.
     * <p>
     * That property associated to the given key will be returned. If there is
     * no property associated to the given key, <code>false</code> is returned
     * </p>
     * @param key the key of the property to set
     * @return value the value of the property
     */
    public abstract boolean getBooleanProperty(String key);
    
    /**
     * Sets a String property in this configuration.
     * <p>
     * That property will be associated to the given key. If there already
     * was a property associated to that key, that property gets overwritten
     * </p>
     * @param key the key of the property to set
     * @param value the value of the property
     */
    public abstract void setStringProperty(String key, String value);
    /**
     * Gets a string property from this configuration.
     * <p>
     * That property associated to the given key will be returned. If there is
     * no property associated to the given key, <code>null</code> is returned
     * </p>
     * @param key the key of the property to set
     * @return value the value of the property
     */
    public abstract String getStringProperty(String key);
    
    /**
     * Gets the list of keys of this configuration
     * @return the list of keys of this configuration
     */
    public abstract  Enumeration<String> getPropertyKeys();
    
    /**
     * Store the given configuration to a file in the filesystem.
     * <p>
     * The name and path of the file where the configuration will be stored is specified by
     * the <code>path</code> parameter. You must have write permissions
     * to write the file.
     * </p>
     * @param path The path of the file where to store the configuration. It must be writable
     * @comments a string of comments to append in the file
     * @throws IOException 
     */
    public abstract void store(String path, String comments) throws IOException;
    
    /**
     * Load the current instance of ConfigurationFileUtil with values
     * read from a file
     * <p>
     * The name and path of the file where the configuration will be read from is specified by
     * the <code>path</code> parameter. You must have read permissions
     * on that file.
     * </p>
     * @param path The path of the file where to read the configuration. It must be readable
     * @throws IOException 
     */
    public abstract void load(String path) throws IOException;
    
    
}
